WhatsApp Flow

O bloco WhatsApp Flow permite integrar e enviar interações em formato Flow dentro do canal WhatsApp, aproveitando os fluxos configurados na mensageria para coletar respostas estruturadas diretamente dos usuários.

Você pode localizar esse bloco no menu lateral de duas formas!

1. Na aba “Canais”, onde ele está disponível por padrão:

2. Pesquisando por “WhatsApp Flow” na barra de busca do menu lateral:

Esse é o bloco "WhatsApp Flow":

Ao acessá-lo, você encontrará os seguintes campos para configuração:

Principais campos:

• Flow selecionado: Aqui deve selecionar o flow, onde após selecionado, serão carregadas as informações do flow, por este motivo, as informações estão sujeitas a carregamento, não aparecendo instantaneamente em tela. Podendo ocorrer um delay ao carregar um flow no bloco de configurações.

• Mensagem inicial do flow: Aqui é definida a mensagem que será enviada junto ao Flow, que suporte até 60 caracteres.

• Mensagem do botão para abrir Flow: Esta será a mensagem que aparecerá dentro do botão responsável por abrir o Flow.

• Perguntas: Aqui são definidas as perguntas do flow, que podem variar dependendo do Flow escolhido. Em cada pergunta será exibida seu Label (não editável), a variável que armazenará a resposta da pergunta (editável), e caso o Flow tenha respostas pré-definidas, também será exibido o campo de Respostas, onde você poderá configurar os botões que o usuário poderá selecionar.

Modelo de Flow com respostas pré-definidas

Além do modelo tradicional com input de texto livre, existe também um modelo de Flow que contém respostas pré-definidas. Neste modelo, ao invés de um campo de entrada de texto, o usuário terá botões pré-definidos para selecionar a resposta.

Ícone de ajuda (?) - Exemplo de JSON dos botões

Ao lado do botão de configurar, você encontrará um ícone de interrogação (?). Ao clicar nele, será exibido um exemplo do formato JSON que os botões devem seguir:

O exemplo mostra a estrutura correta para definir as opções de resposta com botões no Flow do WhatsApp.

A estrutura é dada por:

• id: Um identificador interno da resposta.
• title: O texto que estará no botão de resposta.

Ponto de atenção

É obrigatório seguir exatamente este modelo de estrutura JSON. Qualquer desvio do formato especificado não será aceito pela Meta e o Flow não funcionará corretamente.

O bloco também conta com as funcionalidades padrão dos blocos, como IA, Tags, Ociosidade e Ignorar rota de fuga

Exemplo do bloco em uso

Ponto de atenção

• Para o correto funcionamento deste bloco é indispensável a configuração prévia do canal WhatsApp, disponível nas configurações de canais do bot.

---

Flow com Ponto de Extremidade

O WhatsApp Flows é um recurso da API do WhatsApp Business que permite criar experiências interativas ,como formulários, agendamentos e cadastros, diretamente dentro da conversa. O Ponto de Extremidade (Endpoint) é uma extensão desse recurso que permite que a tela do Flow se atualize dinamicamente sempre que o usuário alterar um campo configurado como ponto de extremidade.

Como funciona

Durante a interação com um Flow, quando o usuário altera um campo que é um ponto de extremidade, a plataforma:

1. Recebe a requisição da Meta com os dados da tela atual.
2. Executa o sub-fluxo configurado para aquele ponto de extremidade.
3. Retorna uma resposta ao Flow (por meio do bloco WhatsApp Flow Endpoint), que pode ser:
   • A mesma tela com os valores atualizados.
   • Uma tela diferente configurada no sub-fluxo.

Regras da estrutura do Flow para integração

Para que os pontos de extremidade funcionem corretamente, é necessário obedecer algumas regras na estrutura do JSON do Flow configurado no portal da Meta.

Hierarquia obrigatória

Os pontos de extremidade devem estar dentro de componentes do tipo Form, respeitando a seguinte hierarquia:

{
  "version": "...",
  "data_api_version": "...",
  "routing_model": {},
  "screens": [
    {
      "id": "...",
      "title": "...",
      "data": {},
      "layout": {
        "type": "...",
        "children": {
          "type": "Form",
          "name": "...",
          "children": ["...componentes..."]
        }
      }
    }
  ]
}

Propriedades do payload

As propriedades do payload enviadas em cada ponto de extremidade (com exceção de cta) devem ser referências ao name de algum dos componentes (children) da tela.

Por exemplo: para utilizar a propriedade dataPagamento no payload, é necessário ter um componente com "name": "dataPagamento" na tela:

[
  {
    "data-source": "${data.ListaFaturasPagamento}",
    "label": "Faturas:",
    "name": "dataPagamento",
    "required": true,
    "type": "CheckboxGroup"
  },
  {
    "label": "Continuar",
    "on-click-action": {
      "name": "data_exchange",
      "payload": {
        "dataPagamento": "${form.dataPagamento}"
      }
    }
  }
]

Atenção ao nome dos componentes

Se a propriedade do payload não corresponder ao name de nenhum componente da tela, o ponto de extremidade não receberá os dados corretamente e poderá resultar em erro.

Configurando o Ponto de Extremidade no bloco

Dentro do bloco WhatsApp Flow, ao selecionar um campo que possui um ponto de extremidade configurado no portal da Meta, será exibida uma opção indicando que ele é um ponto de extremidade. Ao clicar nessa opção, um sub-fluxo será aberto para configuração.

O sub-fluxo do Ponto de Extremidade

O sub-fluxo é o fluxo que define o que acontece ao acionar o ponto de extremidade. Por padrão, ele possui:

• Um bloco Nota com os dados iniciais recebidos da tela (payload da Meta).
• Um bloco de finalização do tipo "WhatsApp Flow Endpoint" (adicionado automaticamente), que é obrigatório e define qual tela será exibida após a execução.

Você pode adicionar outros blocos entre eles, inclusive condicionais, para criar lógicas diferentes de acordo com as escolhas do usuário. Cada bloco de finalização representa um possível destino.

Modelo de dados da tela

Por padrão, o conteúdo enviado de volta ao Flow como resposta de cada ponto de extremidade será o conteúdo da propriedade data da tela configurada no portal da Meta.

Timeout do Ponto de Extremidade

Segundo a documentação oficial da Meta, cada ponto de extremidade possui um timeout de 10 segundos para receber a resposta. Porém, em testes práticos, foi identificado que esse timeout expira em torno de ~8 segundos após a chegada da requisição.

Por este motivo, é necessário considerar o tempo de execução de cada ponto de extremidade para não ultrapassar esse limite.

Atenção — bloco de finalização obrigatório

• Ao executar um ponto de extremidade, é obrigatório que o fluxo termine em um bloco do tipo WhatsApp Flow Endpoint. Sem ele, a requisição não terá resposta e o Flow emitirá erro.
• Caso o fluxo seja interrompido antes de chegar ao bloco de finalização, ou não haja um próximo item definido, a sessão será encerrada.
• Em caso de escape nos blocos dentro de um ponto de extremidade: ao contrário do fluxo padrão (onde a sessão pode ser encerrada), neste caso a sessão não é encerrada, o usuário poderá fechar o Flow, enviar uma mensagem e dar continuidade à conversa normalmente.

Pré-requisito

Para utilizar o Flow com Ponto de Extremidade, você precisa ativar e configurar o recurso nas Configurações do bot → Canais → WhatsApp. Consulte a seção correspondente para mais detalhes sobre como ativar o toggle e registrar o endpoint no portal da Meta.

---

Sincronizar Flow

Ao clicar em um bloco WhatsApp Flow, as informações do flow não são carregadas automaticamente. Para atualizar os dados do bloco com as informações mais recentes do Flow configurado na Meta, utilize o botão Sincronizar.

Isso garante maior controle sobre quando as atualizações são aplicadas ao bloco, evitando alterações inesperadas durante a edição do fluxo.

Flow estático

Para flows sem ponto de extremidade, a sincronização recarrega as informações do flow a partir da Meta e atualiza o bloco.

Após clicar no botão:

• Sucesso: é exibida a notificação Flow sincronizado com sucesso.
• Erro: é exibida a notificação Falha na sincronização do Flow.

Flow com Ponto de Extremidade

Para flows que utilizam pontos de extremidade, a sincronização realiza um merge entre os dados recebidos da Meta e as configurações já existentes no bloco, preservando ao máximo o trabalho já configurado.

O que acontece em cada cenário:

• Novo ponto de extremidade adicionado na Meta: o novo ponto de extremidade passa a aparecer no bloco para configuração.
• Ponto de extremidade removido na Meta: o ponto de extremidade é removido do bloco e todos os blocos e conectores dentro do sub-fluxo correspondente são excluídos.
• Atualização de exemplos de retorno: os valores de exemplo do ponto de extremidade são atualizados no bloco finalizador (botão ?).
• Configurações existentes preservadas: a sincronização não afeta os sub-fluxos já configurados, nem outras configurações do bloco, desde que os pontos de extremidade permaneçam com o mesmo nome (label).

Atenção — renomeação de ponto de extremidade

Se o label de um ponto de extremidade for alterado na Meta, ele será tratado como um ponto de extremidade novo. O ponto anterior será removido junto com seu sub-fluxo, e um novo ponto vazio será adicionado ao bloco.

Se o Flow tiver sido excluído na Meta:

Caso o flow não seja mais encontrado durante uma tentativa de sincronização, nenhum dado do bot é perdido. O bloco passa a exibir uma notificação indicando que o flow está indisponível:

• Notificação no bloco: Flow indisponível — Não foi possível efetuar o sincronismo
• Toaster: Falha na sincronização do Flow

info

Se mais de um bloco no fluxo utilizar o mesmo Flow, cada bloco precisa ser sincronizado individualmente para que as atualizações sejam aplicadas em todos eles.